POST /api/rooms/{roomID}/sandbox/exec

Execute a shell command directly in the room’s sandbox environment

Executes a shell command in the isolated sandbox environment associated with a room. Unlike the message endpoint, this executes commands directly without AI interpretation.

Endpoint

POST /api/rooms/{roomID}/sandbox/exec

Path Parameters

roomID · string · required

Unique identifier for the room. Each room has its own isolated sandbox instance named sandbox-{roomID}.

Request Body

cmd · string · required

The shell command to execute. Must be at least 1 character long.

cmd: z.string().min(1, "Command cannot be empty")

Response

result · ExecResult

The execution result containing stdout and stderr streams.

Show ExecResult Schema

stdout · string

Standard output from the command execution

stderr · string

Standard error output from the command execution

sandboxName · string

The name of the sandbox instance that executed the command (format: sandbox-{roomID}).

Example Request

curl -X POST https://your-worker.workers.dev/api/rooms/room-123/sandbox/exec \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "echo 'Hello from sandbox'"
  }'

Example Response

{
  "result": {
    "stdout": "Hello from sandbox\n",
    "stderr": ""
  },
  "sandboxName": "sandbox-room-123"
}

Error Responses

400 Bad Request

Returned when request validation fails:

{
  "error": "invalid request",
  "details": {
    "cmd": ["Command cannot be empty"]
  }
}

404 Not Found

Returned when the room ID is missing or the endpoint path is incorrect.

405 Method Not Allowed

Returned when using a method other than POST.

500 Internal Server Error

Returned when sandbox execution fails:

{
  "error": "sandbox execution failed: <error details>"
}

Use Cases

• Direct command execution for scripting and automation
• Testing and debugging sandbox environments
• File system operations in the isolated environment
• Running build commands or test suites

Implementation Reference

The handler uses Cloudflare’s sandbox API:

// cf-worker/index.ts:210-242
const sandbox = getSandbox(this.env.Sandbox, `sandbox-${roomId}`);
const result = await sandbox.exec(data.cmd);
return Response.json({ result, sandboxName });

Sandbox Lifecycle

Each room has a persistent sandbox instance that:

• Is created on first use
• Maintains file system state between commands
• Is isolated from other rooms’ sandboxes
• Can be destroyed using the DELETE /api/rooms/ endpoint

Related Endpoints

• POST /api/rooms//message - Send messages to AI (which may execute commands)
• DELETE /api/rooms/ - Destroy the sandbox and clean up room state